HTTX Convertitore da HTML a testo Creato da Gabriele Favrin (E-Mail: favrin@tin.it - FidoNet: 2:333/726.8) Versione 1.7a - Giugno 1998 Indice: 1. Condizioni di utilizzo 2. Proprieta` di HTTX e condizioni di distribuzione 3. Introduzione 4. Richieste hardware e installazione 5. Utilizzo 5.1 Opzioni nella linea di comando 5.2 Configurazione esterna 6. Messaggi di errore e codici di ritorno AmigaDOS 7. FAQ (consigli, interfacciamento ad altri programmi, etc) 8. Informazioni tecniche 8.1 Cosa e` supportato, cosa non lo e` (ancora) e implementazione dello standard. 8.2 Note sulla conversione ANSI 8.3 Note sulla conversione dei contenuti di 
, , <LISTING> e      
          <SCRIPT>.
  9.  Contattare l'autore (bug report, suggerimenti, etc)
 10.  Ringraziamenti
 11.  Storia del programma
 12.  Versioni future



-----------------------------------------------------------------------------

                              *** CHILDWARE ***

Questo  programma  e` "CHILDWARE". L'autore chiede espressamente che chiunque
utilizza  HTTX effettui una donazione ad un ente benefico che opera in favore
dei bambini, in qualunque forma o modo.

Se  non  ne  conoscete  rivolgetevi  all'ufficio  postale della vostra zona e
chiedete informazioni su come effettuare un versamento a favore dell'Unicef.

L'entita` della donazione e` libera, ma fatela!

-----------------------------------------------------------------------------



1.  Condizioni di utilizzo
--------------------------

Prima  di  utilizzare  HTTX  leggere  attentamente  quanto segue e proseguire
soltanto se ci si trova pienamente daccordo.

L'AUTORE  DI  HTTX  NON  SI  ASSUME NE` HA ALCUNA RESPONSABILITA` PER I DANNI
MORALI  E/O MATERIALI CHE L'UTILIZZO DEL SUO PROGRAMMA PUO` CAUSARE A PERSONE
E/O  COSE.  IL  PROGRAMMATORE  SI E` IMPEGNATO A LIMITARE I PROBLEMI CHE HTTX
PUO`  CREARE  MA  NON  E`  IN  GRADO  DI  GARANTIRNE L'EFFICIENZA IN TUTTE LE
SITUAZIONI.  UTILIZZANDO  HTTX  L'UTENTE  SI  ASSUME TUTTE LE RESPONSABILITA`
MORALI, MATERIALI E LEGALI DEL CASO.


ATTENZIONE:

Molti  documenti HTML sono Copyright e non liberamente distribuibili, nemmeno
se  convertiti  in  formato testo.  L'autore declina ogni responsabilita` per
l'utilizzo che verra` fatto dei file generati da HTTX.


Tutti  i  programmi citati in questo documento sono proprieta` dei rispettivi
autori e produttori.



2.  Proprieta` di HTTX e condizioni di distribuzione
----------------------------------------------------

L'eseguibile, il sorgente e le idee alla sua base sono PROPRIETA` ESCLUSIVA
di Gabriele Favrin. Tutti i diritti sono riservati.

HTTX e` freeware, NON pubblico dominio. Puo` essere diffuso a patto che ne`
l'eseguibile, ne` la documentazione vengano in alcun modo alterati. E`
consentita l'archiviazione in formati diversi da LhA ma non la compressione
dei singoli file con PowerPacker o tool simililari.

L'inserimento di HTTX o di sue parti in cover-disk di riviste e` consentito a
patto che venga preventivamente chiesta esplicita autorizzazione all'autore.

L'utilizzo commerciale di questo pacchetto e` consentito esclusivamente ad
AmiTrix e Yvon Rozijn (AWeb).

Gli staff di Aminet, Fred Fish, Meeting Pearls, Amy Resource e CU Amiga
Magazine sono autorizzati ad inserire HTTX nelle rispettive raccolte di
software Pubblico Dominio.



3.  Introduzione
----------------

HTTX (HTml > TXt) e` un programma atto a convertire il formato HTML,
utilizzato per la visualizzazione di file nel World Wide Web e per la
documentazione di diversi programmi, in ASCII puro. Esistono prodotti
analoghi ma poiche` nessuno soddisfaceva pienamente le mie necessita` ho
deciso di creare HTTX. Non dico che sia il migliore o il piu` veloce, ma
certamente introduce diverse funzioni finora inedite nei programmi similari
per Amiga.



4.  Richieste hardware e installazione
--------------------------------------

Sistema richiesto:
Amiga, 512K ram, Kickstart 2.04 (37.175) o superiore.

Occupazione in memoria:
La dimensione del file da convertire e circa 15k fra buffer e altro.

Installazione:
Copiare HTTX nella directory C: o comunque nel path corrente.



5.  Utilizzo
------------

HTTX va lanciato ESCLUSIVAMENTE da Shell.

Sintassi:

HTTX input [output] [opzioni]

I parametri fra parentesi quadre sono opzionali, e` richiesto esclusivamente
il nome del file da convertire ("input").

Qualora non venga indicato un nome per il salvataggio, sara` utilizzata la
convenzione "NomeFile.txt" (es.: test.html verra` salvato come
test.html.txt). Se come output e` indicato un path il file convertito secondo
la convenzione sopra riportata verra` salvato in detta directory.

Alcuni esempi:

-> HTTX data:txt/html/aboxe.html

Il file "aboxe.html" viene convertito e salvato
come "data:txt/html/aboxe.html.txt"

-> HTTX data:txt/html/aboxe.html ram:aboxe.txt

Il file "aboxe.html" viene convertito e salvato
come "ram:aboxe.txt"

-> HTTX data:txt/html/aboxe.html data:txt/

Il file "aboxe.html" viene convertito e salvato
come "data:txt/aboxe.html.txt"



5.1 Opzioni nella linea di comando
----------------------------------

HTTX offre parecchie opzioni per il controllo del documento generato.


LEN
   Lunghezza massima delle linee nel file convertito.

   Default: 77 - Minimo: 15 - Massimo: 255


INDENT o IN
   Dimensione dell'indentazione (giustificazione a destra) per le liste <UL>,
   <OL> e <DL>. Il valore massimo deve consentire almeno due livelli di
   indentazione relativamente alla lunghezza (LEN) impostata.

   Default: 3 - Minimo: 1 - Massimo: il valore di (LEN - 10) / 3


ANSI o AN
   Conversione in ANSI degli stili HTML e dei LINK (HREF e NAME).

   Da non utilizzare se il testo convertito deve essere inserito in aree
   messaggi FidoNet o newsgroup Usenet.

   Leggere il paragrafo 8.2 (note sulla conversione ANSI) per informazioni
   importanti sui codici ANSI utilizzati ed i possibili problemi di
   compatibilita`.

   Default: disattivo (gli stili non vengono convertiti).


7BIT
   Conversione in sequenze di caratteri ASCII minori di 128 delle entita`
   HTML (lettere accentate, etc). Fondamentale per l'inserimento di testi in
   reti come FidoNet dove i caratteri ammessi vanno da 32 a 127.

   ATTENZIONE:  tenere presente che l'opzione ANSI aggiunge i codici ESC
   (ASCII 27) proibiti in FidoNet e fortemente sconsigliati per un uso non
   personale (diffusione) del testo convertito.

   Default: disattivo (i caratteri 8 bit non vengono convertiti).


HRMODE o HR
   I documenti HTML spesso contengono la TAG <HR> che definisce una linea di
   separazione fra i paragrafi. HTTX consente di gestire queste linee in
   diversi modi:

   HRMODE=0
      Le linee non vengono tracciate.
      Equivale all'opzione NOHR delle versioni di HTTX precedenti alla 1.5.

   HRMODE=1
      Le linee vengono tracciate utilizzando il carattere "-".

   HRMODE=2
      Le linee vengono tracciate utilizzando spazi sottolineati (in ANSI).
      In questo modo si ottiene un tratto continuo molto piu` gradevole
      esteticamente.

      Di contro questa soluzione introduce nel documento codici ANSI da
      evitare assolutamente quando il testo e` destinato al forward su
      conferenze echo FidoNet o Newsgroup Usenet.

   Default: HRMODE=1 (le linee vengono tracciate utilizzando il
            carattere "-" ).


NOALIGN o NA
   HTTX supporta l'allineamento (a destra o centrale) di testi e separatori
   (<HR>).

   Esempi (riferiti a una linea a 77 colonne):

                               testo centrato
                                                     testo allineato a destra

   Con l'opzione NOALIGN attiva entrambe le linee sarebbero poste all'inizio,
   con evidente risparmio di caratteri.

   Default: disattivo (l'eventuale allineamento e` supportato).


FILENOTE o FN
   Salvataggio del titolo del documento (<TITLE>) come commento al file.
   Vengono salvati solo i primi 64 caratteri, come da standard HTML.

   Default: disattivo (il titolo viene inserito nel file).


SITE
   Aggiunta all'header del file convertito dell'URL specificato. Utile per
   ricordare da quale documento e` stato ottenuto il file.

   Esempio:
   HTTX ram:children.html SITE=http://www.uncicef.org

   All'inizio del file convertito comparira` il testo
   "URL  : http://www.unicef.org"

   Nota: SITE ha priorita` sull'opzione GETNOTE, quindi specificando un sito
   questo verra` utilizzato anche se la suddetta e` attiva.

   Default: disattivo (omettendo l'opzione e relativo sito
            nulla viene aggiunto).


GETNOTE o GN
   Utilizzo del commento del file da convertire come URL.
   L'opzione sostituisce SITE ed e` utilizzabile con i file salvati dal
   browser AWeb e da tutti i programmi che memorizzano l'URL nel commento.
   La dimensione massima di un commento su AmigaDOS e` di 80 caratteri.

   Default: disattivo.


NOHEADER o NOHEAD
   Soppressione dell'inserimento nel file convertito della versione di HTTX,
   del titolo (<TITLE>) e dell'URL. Qualora indicata l'opzione annulla
   SITE e GETNOTE, se presenti.

   Default: disattivo (la versione di HTTX ed eventuali titolo e URL
            vengono aggiunti).


HREF o LINK
   Inserimento nel file degli indirizzi dei link (TAG <A HREF>).
   Particolarmente utile se il documento da convertire contiene link che si
   vogliono conservare.

   Default: disattivo (i link non vengono aggiunti).


IMG
   Inserimento nel file dell'ALT-Text delle immagini (TAG <IMG>).
   Utile se il documento contiene parecchie immagini con descrizioni
   esplicative.

   Default: disattivo (l'ALT-Text non viene aggiunto).


SCRIPT
   Inserimento nel file del contenuto dell'elemento <SCRIPT>, ad esempio
   script JavaScript.
   Attenzione: questa opzione inserisce lo script stesso, non il risultato
   della sua esecuzione!

   Leggere il paragrafo 8.3 per informazioni importanti sulla conversione di
   questo tipo di testo.

   Default: disattivo (il contenuto dell'elemento <SCRIPT>
            non viene aggiunto).


BADHTML o BAD
   Parziale supporto per documenti realizzati al di fuori degli standard
   HTML. Da utilizzare solo qualora la pagina convertita risulti mancante
   di parti di testo poiche` con documenti corretti si possono avere
   problemi.

   Default: disattivo (HTTX utilizza le regole DTD standard).


FORCE
   Conversione del file specificato senza controllare se si tratta di un
   documento HTML.

   L'UTILIZZO E` A PROPRIO RISCHIO: la conversione di file di testo o
   binari puo` portare ad effetti imprevisti.

   Normalmente HTTX considera valido un file HTML se si verificano una o
   piu` delle seguenti condizioni:

   - estensione .html o .htm
   - TAG iniziale <HTML>
   - TAG iniziale <!DOCTYPE ...>

   L'opzione si rende necessaria se il file non risponde a queste
   caratteristiche pur essendo un documento HTML.

   Default: disattivo (il controllo viene effettuato).


STDIO
   Visualizzazione del file convertito a video invece che su file.
   L'opzione attiva automaticamente QUIET.

   Default: disattivo (il documento viene salvato su file).


PRINT o PRT
   Invio del documento alla stampante invece che a video o su file.

   Il printer.device si occupa di convertire i codici ANSI standard ed il
   fine linea in quelli utilizzati dalla stampante impostata con il
   programma "Printer" presente nel cassetto Prefs.

   Questa opzione va SEMPRE utilizzata qualora si intenda stampare il
   documento convertito, in particolare se l'opzione ANSI e` attiva in quanto
   i codici ANSI utilizzati per la conversione a video o su file sono diversi
   da quelli (necessariamente piu` generici) indirizzati alla stampante.

   Da evitare quindi la soluzione adottata in precedenti versioni di
   HTTX: "HTTX aboxe.html prt:"

   L'opzione attiva automaticamente QUIET e disattiva FILENOTE e STDIO.

   Default: disattivo (il documento viene salvato a video o su file).


APPEND
   Normalmente HTTX sovrascrive il file destinazione indicato, se gia`
   presente.

   Utilizzando APPEND il testo convertito viene invece aggiunto in coda al
   file specificato.

   Default: disattivo (il file destinazione, se gia` esistente, viene
            sovrascritto).


NOCFG
   HTTX per default carica la configurazione ENV:httx.prefs (se non
   diversamente specificato dall'opzione CFG). Con questa opzione HTTX
   utilizza solo le impostazioni di default o quelle inserite nella linea di
   comando.

   Per informazioni sulla configurazione esterna vedere il paragrafo 5.2.

   Default: disattivo (HTTX cerca la configurazione di default o quella
            specificata con l'opzione CFG).


CFG
   Con questa opzione e` possibile specificare il nome della configurazione
   utilizzata da HTTX. Tale file deve trovarsi nella directory ENV:

   L'opzione disattiva NOCFG.
   Per informazioni sulla configurazione esterna vedere il paragrafo 5.2.

   Default: disattivo (HTTX cerca di caricare la configurazione httx.prefs).


INCLUDE
   Con questa opzione e` possibile far precedere da un altro file di testo
   il documento HTML da convertire.

   Il file incluso NON VIENE ALTERATO IN ALCUN MODO, compresi eventuali
   caratteri 8 bit, wordwrap del testo, codici ANSI e via dicendo. HTTX non
   segnalera` se sono presenti caratteri 8 bit.

   Tenerne conto se il testo convertito deve essere inserito in conferenze
   echo FidoNet o Newsgroup Usenet.

   Default: disattivo (nessun testo viene aggiunto).


QUIET
   Soppressione dei messaggi a video di HTTX. L'opzione si rivela utile se
   il programma e` usato all'interno di uno script.

   ATTENZIONE: viene disabilitata anche la visualizzazione dei messaggi
   d'errore. Restano pero` attivi i codici d'errore AmigaDOS.

   Default: disattivo (l'output di HTTX viene visualizzato).


Se non specificato diversamente vengono utilizzate le impostazioni di
default.

Al termine della conversione, se l'opzione QUIET non e` attiva, vengono
fornite le seguenti informazioni:

- dimensione dei file di input e output.
- eventuale presenza di caratteri a 8 bit (e se attiva, loro conversione a
  7 bit).
- eventuale presenza di TAB o caratteri ASCII minori di 32 non convertiti in
  quanto inclusi in testo preformattato.
- eventuale presenza di commenti HTML non conformi agli standard. Un
  commento HTML mal scritto puo` rendere invisibili intere parti del
  documento. Se il file convertito appare incompleto, provare ad utilizzare
  l'opzione BADHTML.



5.2 Configurazione esterna
--------------------------

HTTX supporta una configurazione esterna, ovvero un file di testo in cui e`
possibile inserire le opzioni piu` frequentemente utilizzate per non doverle
ribattere ad ogni esecuzione.

Di default (a meno che sia specificata l'opzione NOCFG o che CFG non indichi
un file diverso) HTTX cerca il file "ENV:httx.prefs".

E` possibile utilizzare piu` configurazioni, ad esempio una per la
conversione su file ed una per la stampa, creando file differenti ed
utilizzando l'opzione CFG nome file (non e` necessario indicare ENV:).

Esempio:

-> HTTX aboxe.html

Converte il file "aboxe.html" utilizzando la configurazione di default
(ENV:httx.prefs).

-> HTTX aboxe.html PRINT CFG=httxprt.prefs

Converte il file "aboxe.html" utilizzando la configurazione contenuta nel
file ENV:httxprt.prefs



Parametri utilizzabili
----------------------

La configurazione esterna supporta un sottoinsieme delle opzioni disponibili
in linea di comando. Ogni opzione DEVE essere specificata nella forma estesa
(ad esempio ANSI e non AN, INDENT e non IN, etc).

Il file non deve contenere altro se non le opzioni (ed eventuali parametri).
E` consentito andare a capo per maggiore chiarezza in fase di stesura.

I comandi disponibili, per la cui descrizione si rimanda al paragrafo 5.1,
sono:

LEN      - dimensione massima delle linee.
INDENT   - dimensione dell'indentazione.
ANSI     - utilizzo dei codici ANSI nella conversione.
7BIT     - conversione a 7 bit delle entita` HTML 8 bit.
HRMODE   - modalita` tracciamento linee di separazione.
NOALIGN  - disattivazione allineamento (centrale o a destra) del testo.
FILENOTE - salvataggio del titolo del documento HTML come commento al file
           convertito.
GETNOTE  - utilizzo del commento al file originale come URL del file da
           convertire.
NOHEADER - omissione dell'instestazione (versione di HTTX, URL e titolo
           del documento originale) nel file convertito.
HREF     - aggiunta dei link (<A HREF>) al file convertito.
IMG      - aggiunta dell'ALT-Text delle immagini al file convertito.
SCRIPT   - aggiunta del contenuto dell'elemento <SCRIPT>.
BADHTML  - parziale supporto per HTML non conforme agli standard.

Gli argomenti in linea di comando hanno priorita` rispetto a quelli inseriti
nella configurazione esterna e funzionano come interruttori. Alcuni esempi:

Posta una configurazione esterna contenente:

IMG GETNOTE LEN=70

inserendo il comando:

-> HTTX aboxe.html IMG

si ottiene che IMG e` presente sia nella configurazione che lo attiva che
nella linea di comando che lo disattiva.

-> HTTX aboxe.html LEN=74

LEN e` presente nella configurazione esterna, ma viene preso il valore
impostato in linea di comando ovvero 74.



Creazione e modifica della configurazione
-----------------------------------------

I file di configurazione in effetti sono vere e proprie variabili di sistema
e si trovano nelle directory ENVARC: (su disco) ed ENV: (generalmente in
ram). Questa distribuzione consente di modificare le configurazioni anche in
maniera non permanente in quanto il contenuto di ENV: vale solo per la
sessione in corso e viene resettato ai contenuti di ENVARC: ad ogni
accensione o reset della macchina.

Di contro per salvare una configurazione in maniera permanente sara`
necessario copiare lo stesso file sia in ENV: che in ENVARC:.

Utilizzare il proprio editor di testi preferito (per esempio Ed, Cygnus
Editor, GoldEd, etc) per creare il file il cui nome di default e` httx.prefs.
Salvarlo in ENV: ed ENVARC: in modo che non venga perso al reset successivo.
Modifiche temporanee possono essere effettuate editando il file in ENV:.

La configurazione di HTTX puo` essere interamente gestita utilizzando il
plugin per il browser WWW AWeb.



6.  Messaggi di errore e codici di ritorno AmigaDOS
---------------------------------------------------

Al termine dell'esecuzione HTTX genera l'appropriato codice d'errore (RC)
AmigaDOS, utilizzabile all'interno di script per determinare l'esito della
conversione. Per la lista completa dei codici si rinvia al manuale AmigaDOS.

In caso di errore, se l'opzione QUIET non e` attiva, viene visualizzato anche
il messaggio AmigaDOS relativo.

Segue un elenco degli errori piu` frequenti e del loro significato. Da notare
che se il sistema e` localizzato i messaggi sono visualizzati nella lingua
impostata. Fare riferimento al manuale AmigaDOS per informazioni piu`
dettagliate.

Argument line invalid or too long
   Gli argomenti inseriti sono errati.

*** Break
   La conversione e` stata interrotta con la sequenza Control-C od il comando
   break ed il file di output e` stato cancellato.

Not enough memory available
   Non c'e` sufficiente memoria libera per allocare i buffer utilizzati da
   HTTX.
   Questa condizione puo` verificarsi qualora il file da convertire o quello
   da includere siano troppo grandi o la memoria risulti troppo frammentata.
   Provare a resettare Amiga.

Object not found
   Il file indicato non esiste o non e` accessibile.
   Verificare l'esattezza di nome e percorso del file.

Object is not of the required type
   Il file indicato non sembra in formato HTML.
   Se si ritiene che lo sia utilizzare l'opzione FORCE.


HTTX inoltre puo` visualizzare altri errori, in inglese, relativi all'errato
utilizzo di comandi od opzioni.


The line length must be between 15 and 255 characters (current is NN)
   La dimensione di linea inserita e` maggiore di 255 o minore di 15
   caratteri.

Indentation size must be at least 1 (current is NN)
   La dimensione dell'indentazione dev'essere almeno di un carattere.

With line length XX, indentation size YY, max indent level is ZZ.
You must allow at least 3 indentations.
   Il massimo livello di indentazione, relativamente alla lunghezza linea e
   all'indentazione impostata, e` minore di 3.

HRMODE value must be 0, 1 or 2
   Il valore impostato per l'opzione HRMODE non e` valido.
   Deve essere 0, 1 o 2.


Infine possono essere visualizzati degli avvertimenti (Warning) che non
precludono la conversione del documento ma possono indicare situazioni che
alterano il risultato finale:


Error in env config. HTTX will use its defaults
   La configurazione esterna contiene un errore che ne ha impedito
   l'interpretazione. HTTX utilizzera` le impostazioni di default e gli
   eventuali argomenti inclusi nella linea di comando.

   Fare riferimento al paragrafo 5.2 per informazioni sul formato da
   utilizzare.

ENV config 'NAME' not found.
   La configurazione specificata con l'opzione CFG non e` stata trovata.
   HTTX utilizzera` le impostazioni di default e gli eventuali argomenti
   inclusi nella linea di comando.
   Il file di configurazione deve trovarsi in ENV:. Ricordarsi di copiarlo in
   ENVARC: quando lo si crea per la prima volta o lo si modifica.

Found non-ASCII chars in preformatted text!
   In una sezione di testo non formattato sono stati trovati caratteri a
   8 bit. Tenerne conto se il testo convertito deve essere inserito in
   conferenze echo FidoNet o Newsgroup Usenet.

This file contains non standard HTML comment(s)!
   Il file potrebbe non essere stato convertito completamente in quanto
   sono stati trovati commenti HTML non standard. Se il file convertito
   appare incompleto, provare ad utilizzare l'opzione BADHTML.

Include file could not be added.
   Il file specificato con l'opzione INCLUDE non puo` essere aggiunto
   perche` non esiste o non e` accessibile.
   Verificare l'esattezza di nome e percorso del file.



7.  FAQ (consigli, interfacciamento ad altri programmi, etc)
------------------------------------------------------------

Q. "Gli stili ANSI (grassetto, italico, sottolineato, blu) vengono
   interrotti dopo la prima linea."
A. Vedere il paragrafo 8.2.

Q. "Il testo converito da HTTX non e` centrato mentre nella pagina
   originale lo e`."
A. Questo puo` avvenire se il testo nelle linee di una tabella (<TR>) o nelle
   sue celle (<TD>) e` definito come centrato. Per mantenere la
   compatibilita` con alcuni programmi utilizzati in congiunzione ad HTTX,
   questa versione non supporta l'allineamento definito in tali elementi.
   Verra` aggiunto in versioni future che avranno maggiore supporto per le
   tabelle.

Q. "In alcuni casi non funziona l'allineamento, il wordwrap e le liste non
   vengono formattate correttamente o addirittura compaiono TAG HTML".
A. Si tratta di testo preformattato contenuto nell'elemento <PRE>. HTTX lo
   copia cosi` com'e`, senza effettuare alcuna formattazione. Questa scelta
   deriva dal fatto che sovente i testi di questo tipo contengono sorgenti
   che l'autore del documento desidera conservare cosi` come sono.

   Negli elementi <LISTING> e <XMP> anche le TAG vengono lasciate cosi` come
   sono, come da specifiche. Anche se le direttive dell'HTML 4.0 sconsigliano
   <XMP> esso e` tuttora utilizzato per contenere esempi in molti documenti,
   come le specifiche JavaScript di Netscape.

Q. "Determinate pagine non vengono convertite correttamente..."
A. Le ragioni possono essere diverse: layout basato su tabelle (attualmente
   non supportate completamente, si veda paragrafo 8.1), errori nel sorgente
   HTML (HTTX e` abbastanza tollerante, ma ci sono dei limiti) oppure errori
   nel parser HTML di HTTX stesso. Se ritenete che la pagina sia corretta,
   segnalatemene l'URL.
   (E-Mail: favrin@tin.it, FidoNet: 2:333/726.8)

Q. "Posso utilizzare HTTX direttamente da AWeb o Directory Opus?"
A. Per quanto riguarda AWeb, gli utenti della versione 3.1 o successiva
   possono utilizzare il plugin ARexx fornito.

   HTTX puo` essere utilizzato anche da Directory Opus creando un bottone
   configurato come segue (esempio relativo alla versione 4.12):

   New Entry/AmigaDOS:
     C:HTTX {f} {d}
     (sostituire a C: il path completo se HTTX non si trova li`)

   In questo modo il file selezionato nella directory "source" verra`
   convertito in formato testo e salvato nella directory "destination".

   Attivando il flag "Do all files" diventa possibile convertire piu` files
   alla volta semplicemente selezionandoli e attivando il bottone HTTX.

Q. "Utilizzo un programma che si appoggia ad HTTX per la stampa dell'HTML.
   Installando una versione di HTTX superiore alla 1.1b la stampa non
   funziona piu`."
A. Diversi programmi che si appoggiano ad HTTX sono stati realizzati ai tempi
   della versione 1.1b. Essi usano comandi tipo "HTTX <nomefile> prt:".
   Questa sintassi non e` piu` utilizzabile, soprattutto se viene abilitata
   l'opzione ANSI. A partire dalla versione 1.5, infatti, HTTX utilizza
   per la stampa alcuni codici ANSI non compatibili con "prt:".

   La soluzione piu` semplice e` sostituire "prt:" con PRINT o PRT. Esempio:

   HTTX %s prt: ANSI
   (utilizzato da MoreHTML)

   Diventa:

   HTTX %s PRT ANSI

Q. "Posso migliorare le prestazioni di HTTX?"
A. E` possibile velocizzare la conversione utilizzando un filesystem con
   blocchi da 1024 byte, ad esempio il ram disk. Nel caso la memoria sia
   poca o particolarmente frammentata il salvataggio in ram portera` pero` a
   rallentamenti.



8.  Informazioni tecniche
-------------------------

Questo paragrafo affronta alcune tematiche relative allo standard HTML ed
alla sua implementazione in HTTX. Anche se la sua lettura non e` fondamentale
per imparare ad utilizzare il programma, sono presenti informazioni
importanti, da leggere se si intende diffondere i testi convertiti.



8.1 Cosa e` supportato, cosa non lo e` (ancora) e implementazione
    dello standard.
-----------------------------------------------------------------

HTML supportato:

 - Le entita` descritte nel RFC 1866, &copy; e &reg; (NHTML), le entita`
   numeriche (sia decimali che esadecimali), le entita` numeriche ed i
   caratteri speciali di Win'95.
 - I separatori (<CENTER>, <DIV>, <BR>, <P> e <HR>) e il cambio dimensione
   font (da <H1> ad <H6>).
 - L'allineamento (centrale e a destra) di testo (intestazioni e paragrafi) e
   separatori.
 - Gli stili fisici e logici.
 - Liste numerate (<OL>, con eventuale attributo START), non numerate (<UL>)
   e liste di definizioni (<DL>) fino a un massimo di 255 livelli.
 - Il titolo del documento (<TITLE>).
 - I link (<HREF>), le mappe utente e le immagini (<IMG> con eventuale
   ALT-text).
 - Il testo preformattato (<PRE>, <XMP> e <LISTING>).
 - Gli script (il contenuto di <SCRIPT>).
 - L'utilizzo non standard di "<" e ">" in un testo preformattato
   (suscettibile di cambiamenti).

Cosa non e` (ancora completamente) supportato:

 - Le tabelle (<TABLE>). Attualmente ogni cella e` gestita come un documento
   a parte con un proprio allineamento, livello di indentazione liste, stili
   e via dicendo.
 - <APPLET> e <STYLE>: non potendoli gestire il loro contenuto viene
   ignorato.

Implementazione dello standard:

 - TAG sconosciute vengono ignorate.
 - Doppi spazi, spazi a inizio e fine riga vengono eliminati,
 - Caratteri ASCII non visualizzabili (minori di 32) vengono convertiti in
   spazi.
 - EOL PC (CR+LF) e Mac (CR) vengono convertiti nel formato Amiga (LF).
 - Per facilitare la lettura del testo nelle tabelle, <TD> viene trasformato
   in uno spazio e <TR> in un EOL. Inoltre fra due <TR> (table row) viene
   inserito al massimo un separatore (<HR>).
 - EOL consecutivi vengono ridotti ad uno (fatta eccezione per <BR>).

Queste regole non vengono seguite durante la conversione degli elementi
<SCRIPT>, <PRE>, <LISTING> e <XMP>. Fare riferimento alla sezione 8.3 per
maggiori informazioni.



8.2 Note sulla conversione ANSI
-------------------------------

Se l'opzione ANSI e` attiva HTTX utilizza le sequenze ANSI per la gestione
degli stili HTML (come grassetto, italico, sottolineato etc), dei link
(visualizzati in blu sottolineato), del centraggio e dell'indentazione del
testo.

I codici ANSI utilizzati sono stati tratti dalle specifiche dello standard e
dovrebbero essere supportati da qualunque programma (forse...).

Queste le sequenze (ESC e` sostituito da "\e").

Grassetto     \e[1m
Italico       \e[3m
Sottolineato  \e[4m
Blu           \e[33m

La definizione contemporanea di piu` stili viene effettuata con ";", ad
esempio per impostare grassetto e italico HTTX utilizza "\e[1;3m".

Per l'indentazione delle liste e l'allineamento del testo viene utilizzata la
sequenza di posizionameto cursore "\e[nnC" dove nn e` il numero di
spostamenti a destra da effettuare. Questa sequenza non e` usata in fase di
stampa.


Problematiche di compatibilita`:

- Lo standard ANSI prevede che il fine linea non causi l'interruzione di uno
  stile, quindi se uno stile risulta interrotto dopo la prima linea il
  problema e` nei programmi utilizzati per visualizzare il testo. Sia la
  shell standard che MultiView, per citarne due, operano correttamente.

- Sembra che MultiView 40.8 non supporti le sequenze di posizionamento
  cursore. Se con MultiView una pagina contenente liste o testo allineato
  appare mal convertita, provare a ripetere la conversione disattivando
  l'opzione ANSI oppure utilizzare un diverso visualizzatore di testi.



8.3 Note sulla conversione dei contenuti di <PRE>, <XMP>,
    <LISTING> e <SCRIPT>.
---------------------------------------------------------

Le regole indicate nell'implementazione dello standard (paragrafo 8.1), il
wordwrap e la conversione a 7 bit dei caratteri 8 bit non sono totalmente
valide per alcuni elementi che in base alle specifiche HTML vengono gestiti
diversamente.

- Elemento <PRE> (testo preformattato).
  In questa modalita` il wordwrap non e` effettuato. L'interpretazione delle
  TAG HTML (ad eccezione di liste e allineamento) viene effettuata. Le
  entita` numeriche minori di 32 non vengono convertite per evitare
  problemi con file uuencodati presenti nelle pagine HTML.

- Elementi <XMP>, <LISTING> e <SCRIPT>.
  Il contenuto di questi elementi e` lasciato inalterato. Non sono effettuati
  wordwrap, conversione delle entita` ed interpretazione delle TAG. Se
  l'opzione 7BIT e` attiva i caratteri ASCII minori di 32 vengono convertiti
  in spazi. Quelli maggiori di 128 vengono lasciati come sono (le entita` di
  Win'95 non vengono convertite). Tenerne conto se il testo convertito deve
  essere inserito in conferenze echo FidoNet o Newsgroup Usenet.



9.  Contattare l'autore
-----------------------

Oltre a consigli, segnalazioni di bug, problemi, e` gradito un messaggio di
commento da chiunque utilizzi HTTX, oltre che naturalmente segnalazioni di
azioni in favore di enti che si occupano di bambini (vedi "CHILDWARE").

E-Mail:  favrin@tin.it
FidoNet: 2:333/726.8

Per favore scrivete in italiano o in inglese.

Pagina di supporto per HTTX:
http://freeweb.aspide.it/free/poing/soft/httx/indice.html



10.  Ringraziamenti
-------------------

Per il betatesting:

Claudio Mazzuco       kirk@maya.dei.unipd.it
William Parker        wparker@bill.amitrix.com
Giuseppe Pasanisi     amicus@net-service.net
Giuseppe Ammendolia   ryuga@freenet.hut.fi
Neil Bothwick         aweb@wirenet.co.uk
Marco L. Buschini     shido@mclink.it

Per la documentazione inglese e la verifica dei testi:

Fabio Belli           zak@anturio.com
William Parker        wparker@bill.amitrix.com

Per il betatesting del Plugin per AWeb:

William Parker        wparker@bill.amitrix.com
Dale Currie           dalec@zorro.amitrix.com

Grazie di cuore a Yvon Rozijn per aver voluto HTTX nel pacchetto di AWeb II e
per tutto l'aiuto che mi ha fornito!

Grazie a W. v. Oortmerssen per lo splendido AmigaE con cui e` stato
realizzato HTTX.

Infine un ringraziamento speciale a chi mi ha scritto a proposito di HTTX e a
chi lo utilizza!



11.  Storia del programma
-------------------------

V1.0 (Luglio 1996)
   Prima versione pubblica.

V1.1 (Novembre 1996)
  +Migliorata la velocita`.
  +Aggiunte le opzioni STDIO, QUIET, BADHTML, NOHEADER, GETNOTE.
  +Aggiunto il supporto per i codici d'errore AmigaDOS.
  +Aggiunto il supporto per le TAG <ADDRESS> e <LISTING>.
  +Modificata la gestione di <BR> e <LI> in ottemperanza all'implementazione
   nello standard HTML 3.2.
  +Riscritta la gestione delle entita`: ora vengono convertite anche se non
   chiuse da ";".
  +Estesa la conversione a 7 bit, ora piu` veloce, completa (vengono
   convertiti quasi tutti i caratteri) e accurata (non vengono lasciati
   accenti in mezzo alle parole, ad esempio "httx è bello" diventa
   "httx e` bello" mentre "Belphégor" diverra` "Belphegor".
  +A grande richiesta impostata come disattiva per default l'opzione 7BIT.
  +Migliorato il supporto per commenti multilinea e sorgenti HTML non
   standard.
  +Aggiunto il supporto per TAG e ALT-Text contenenti LF o "<" e ">".
  -Corretti diversi piccoli bug estetici nella conversione (doppi spazi in
   alcune circostanze, spurie all'uscita da <PRE> e <SCRIPT> e altro).
  -Corretto un errore che poteva portare al lock del file da convertire.
  -Corretto un errore in FILENOTE.

V1.1a (Gennaio 1997)
  -Corretto uno stupido e raro bug nella gestione delle TAG.
  -Corretta la gestione degli EOL MAC.

V1.1b
  -Corretta l'interpretazione di alcune entita`.

V1.5 (Maggio 1997)
  +Velocizzato di molto il programma grazie ad una completa riscrittura del
   parser HTML e all'ottimizzazione di parecchie funzioni.
  +Aggiunte le opzioni HRMODE, NOALIGN, PRINT, APPEND, NOCFG, CFG.
  +Aggiunto il supporto per l'allineamento (centrale e a destra) di testo e
   separatori.
  +Aggiunto il supporto per varie TAG e attributi HTML (ad esempio START
   nelle liste numerate).
  +Ottimizzato l'output ANSI.
  +Aggiunto il supporto per i separatori in ANSI.
  +Aggiunto il supporto per la configurazione esterna.
  +Migliorato il supporto delle entita` che ora vengono identificate
   qualunque sia il carattere che le chiude.
  +Resi piu` esplicativi i messaggi d'errore interni di HTTX e sostituiti
   quelli DOS con PrintFault() di AmigaDOS.
  +Aggiunto il supporto per "HTTX nome_sorgente path_destinazione".
  +Migliorata la gestione dei separatori nelle tabelle.
  -Ora HTTX segue piu` fedelmente i DTD HTML per parecchie TAG.
  -Corretti alcuni errori nel wordwrap.
  -Corretti tutti i bug segnalati per la 1.1b.
  +... e molte altre migliorie!

V1.7 (Gennaio 1998)
  +Riscritte in maniera piu` lineare varie parti importanti del sorgente come
   la gestione ANSI ed il wordwrap.
  +Reso il parser HTML piu` fedele alle regole SGML.
  +Migliorato il supporto delle tabelle tramite la gestione di ogni cella
   come un documento a parte.
  +Aggiunto il supporto per le entita` numeriche esadecimali (&#xnn;)
   (fino a 255) e le entita` numeriche ed i caratteri speciali di Win'95 fra
   128 e 159.
  +Aggiunto il supporto per le TAG <SELECT>, <XMP> e migliorata la gestione
   di <LISTING>.
  +Il testo interno a <BLOCKQUOTE> (o <BQ>) ora viene indentato.
  +In modalita` <PRE> le entita` numeriche minori di 32 vengono lasciate
   inalterate.
  +Aggiunte le opzioni SCRIPT e INCLUDE.
  +Specificando l'opzione NOHEADER ora la versione di HTTX non viene
   inserita.
  +Migliorato il supporto per HTML non standard.
  +... e molte altre migliorie!
  -Corretti vari piccoli bug estetici o dovuti ad HTML non standard.
  -Risolti parecchi problemini del vecchio wordwrap (il piu` rilevante dei
   quali si manifestava quando una linea senza spazi terminava con una
   entita`).
  -Entita` numeriche inferiori ad ASCII 32 non erano convertite in spazi.
  -In caso di argomenti errati potevano venire visualizzati errori
   inesistenti.
  -In alcuni casi l'ultimo carattere del file poteva essere ignorato.
  -Spazzati via diversi altri piccoli bug!

V1.7a (Giugno 1998)
  +Aggiunto l'alias PRT per l'opzione PRINT.
  -Corretto un pericoloso bug che poteva portare al crash di HTTX 
   durante l'allineamento di linee molto lunghe.
  -Corretto un errore nel wordwrap che causava problemi di layout dopo certe
   linee.



12.  Versioni future
--------------------

HTTX e` un programma in continuo sviluppo, se non altro perche` lo utilizzo
quotidianamente e ne rilevo quindi mancanze o possibili migliorie. Questa
versione ha posto le basi per una nuova, ancor migliore, che sara` presto
disponibile.



-----------------------------------------------------------------------------

                              *** CHILDWARE ***

Questo  programma  e` "CHILDWARE". L'autore chiede espressamente che chiunque
utilizza  HTTX effettui una donazione ad un ente benefico che opera in favore
dei bambini, in qualunque forma o modo.

Se  non  ne  conoscete  rivolgetevi  all'ufficio  postale della vostra zona e
chiedete informazioni su come effettuare un versamento a favore dell'Unicef.

L'entita` della donazione e` libera, ma fatela!

-----------------------------------------------------------------------------